KCFindFirstItem

KCFindFirstItem
Header:	Keychain.h		Carbon status:	Under Evaluation

Finds the first keychain item in a specified keychain that matches specified attributes.

OSStatus KCFindFirstItem (
    KCRef keychain, 
    const KCAttributeList *attrList, 
    KCSearchRef *search, 
    KCItemRef *item
);

keychain: A reference to the keychain that you wish to search. If you pass a locked keychain, the Unlock Keychain dialog box is displayed. If you pass NULL, KCFindFirstItem search all unlocked keychains.
attrList: A pointer to a list of 0 or more structures containing information about the keychain item attributes to be matched. Pass NULL to match any attribute.
search: On return, a pointer to a reference to the current search criteria.
item: On return, a pointer to the first matching keychain item.

function result: A result code. The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCItemNotFound indicates that no matching keychain item was found. The result code errKCNoSuchAttr indicates that the specified attribute is undefined for this item class.

DISCUSSION

The KCFindFirstItem function finds the first keychain item matching a list of zero or more specified attributes in the specified keychain. KCFindFirstItem returns a reference to the matching item and the current search criteria. You can use the returned search criteria for subsequent calls to the function KCFindNextItem.

SPECIAL CONSIDERATIONS

When you are completely finished with the search, call the functions KCReleaseItem and KCReleaseSearch to release the keychain item reference and search criteria reference, respectively.

VERSION NOTES

Available beginning with Keychain Manager 1.0.

AVAILABILITY

Under evaluation for Carbon. Available in CarbonLib 1.0 and later when KeychainLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by KeychainLib 1.0 and later.